import { graphql } from 'gatsby';

import Callout from '../../components/Callout';
import ComponentApi from '../../components/ComponentApi';
import ReactPlayground from '../../components/ReactPlayground';

import PlaceholderAnimation from '../../examples/Placeholder/Animation';
import PlaceholderCard from '../../examples/Placeholder/Card';
import PlaceholderColor from '../../examples/Placeholder/Color';
import PlaceholderExample from '../../examples/Placeholder/Example';
import PlaceholderSize from '../../examples/Placeholder/Size';
import PlaceholderWidth from '../../examples/Placeholder/Width';

# Placeholders

<p className="lead">
  Use loading placeholders (otherwise known as "skeletons") for your components
  or pages to indicate something may still be loading
</p>

## About

Placeholders can be used to enhance the experience of your application. They’re
built only with HTML and CSS, meaning you don’t need any JavaScript to create them.
You will, however, need some custom JavaScript to toggle their visibility. Their
appearance, color, and sizing can be easily customized with our utility classes.

## Example

In the example below, we take a typical card component and recreate it with placeholders
applied to create a “loading card”. Size and proportions are the same between the two.

<ReactPlayground codeText={PlaceholderCard} />

## How it works

Create placeholders with the `Placeholder` component and a grid column prop (e.g., `xs={6}`)
to set the `width`. They can replace the text inside an element or be added to an existing
component via the `as` prop.

Additional styling is applied to `PlaceholderButton`s via `::before` to ensure the `height`
is respected. You may extend this pattern for other situations as needed, or add a `&nbsp;`
within the element to reflect the height when actual text is rendered in its place.

<ReactPlayground codeText={PlaceholderExample} />

<Callout>
  The use of <code>aria-hidden="true"</code> only indicates that the element
  should be hidden to screen readers. The <i>loading</i> behaviour of the
  placeholder depends on how authors will actually use the placeholder styles,
  how they plan to update things, etc. Some JavasSript code may be needed to{' '}
  <i>swap</i> the state of the placeholder and inform AT users of the update.
</Callout>

## Width

You can change the `width` through grid column classes, width utilities, or inline styles.

<ReactPlayground codeText={PlaceholderWidth} />

## Color

By default, the `Placeholder` uses `currentColor`. This can be overriden with a custom color
or utility class.

<ReactPlayground codeText={PlaceholderColor} />

## Sizing

The size of `Placeholder`s are based on the typographic style of the parent element.
Customize them with sizing props: `lg`, `sm`, or `xs`.

<ReactPlayground codeText={PlaceholderSize} />

## Animation

Animate placeholders by setting the prop `animation` to `glow` or `wave` to better
convey the perception of something being _actively_ loaded.

<ReactPlayground codeText={PlaceholderAnimation} />

## API

<ComponentApi metadata={props.data.Placeholder} />
<ComponentApi
  metadata={props.data.PlaceholderButton}
  exportedBy={props.data.Placeholder}
/>

export const query = graphql`
  query Placeholder {
    Placeholder: componentMetadata(displayName: { eq: "Placeholder" }) {
      displayName
      ...ComponentApi_metadata
    }
    PlaceholderButton: componentMetadata(
      displayName: { eq: "PlaceholderButton" }
    ) {
      ...ComponentApi_metadata
    }
  }
`;
